Skip to content

fix(types): encode a beacon state without holding it twice - #741

Merged
pablodeymo merged 8 commits into
fix/storage-latest-messages-exact-growthfrom
fix/types-state-encode-without-regrowth
Nov 18, 2026
Merged

pablodeymo merged 8 commits into
fix/storage-latest-messages-exact-growthfrom
fix/types-state-encode-without-regrowth

Conversation

@MegaRedHand

@MegaRedHand MegaRedHand commented Oct 30, 2026 •

Copy link
Copy Markdown
Collaborator

🗒️ Description / Motivation

libssz's container encoder writes each fixed-size field past the end of the buffer and then moves it into place, and its to_ssz reserves only the encoding's length. So when a state's last field is fixed-size, encoding it reallocates a buffer the size of the whole state to twice that, copying it, just for that last field. Fulu's state ends on proposer_lookahead, gloas's on ptc_window. A 44 MB fulu state encoded with plain to_ssz ended in an 88 MB buffer.

On a mainnet state (hundreds of MB) that is one extra state-sized copy per encode. Two places pay it:

  • The state writer, on every import. encode_state_value encoded the state, then copied it into a second buffer behind its fork tag. At a snapshot, the writer also cloned the result, one copy for the States row and one for its snapshot memo.
  • The Beacon API's SSZ state response, /eth/v2/debug/beacon/states/{state_id}, on every request.

What Changed

  • crates/common/types/src/beacon/containers/mod.rs:
    • BeaconState::ssz_append_capacity(): the encoding's length plus the largest fixed-size field of that variant's state. The beacon forks share one list; a lean state has its own, since its widest fixed field is a block header, not 2 MiB.
    • BeaconState::ssz_append(buf) reserves that much past buf's current length, then appends the encoding. A caller with a prefix (the fork tag) needs no sizing of its own.
    • BeaconState::to_ssz() goes through ssz_append instead of libssz's to_ssz. That fixes every caller of the enum, the API response included.
  • crates/storage/src/state_codec.rs: encode_state_value pushes the fork tag, then appends the state into the same buffer.
  • crates/storage/src/state_writer.rs, api/traits.rs, backend/rocksdb.rs: a snapshot write no longer clones the encoded state. The plan hands over one buffer and a memoize_snapshot flag; the writer puts it into the batch from a borrow, through a new StorageWriteBatch::put(table, &key, &value), then moves the same buffer into the memo.

Correctness / Behavior Guarantees

  • Same bytes as before; only the allocation changes.
  • The headroom is the largest fixed-size field (randao_mixes on mainnet, 2 MiB; ptc_window on minimal). Any fixed-size field can then be written past the end, wherever it sits in the container, so the bound holds for every fork, including the earlier ones whose state also ends on a fixed-size field (phase0's finalized_checkpoint, altair's next_sync_committee).
  • The returned Vec carries that headroom as spare capacity: a few MiB at most, next to a state of hundreds of MB.
  • A snapshot write now holds the encoded state plus RocksDB's own copy in the batch until commit, instead of three copies.
  • Callers that encode a per-fork struct directly still go through libssz's to_ssz. I found none outside tests.
  • Deferred: fixing the overhang in libssz itself would cover blocks and sidecars too, but needs a libssz PR and a rev bump.

Tests Added / Run

  • ssz_append_never_regrows_a_buffer_with_its_capacity_to_spare, in state_transition's helpers/test_state.rs (the one place a state of every fork is built): a small state of every fork, phase0 through gloas, plus a lean genesis with no validators. to_ssz and an append after a one-byte prefix both reserve exactly the capacity and never regrow, and the encoding round-trips. Run on both presets. Verified to fail for the lean case without its own headroom.
  • a_beacon_state_value_is_its_tag_then_its_ssz_in_one_buffer: the tag byte, then the state's SSZ, in one buffer of exactly the reserved capacity. The value round-trips through decode_state_value.
  • The shared backend suite checks the new put against RocksDB and the in-memory backend.
  • cargo test --profile release-fast -p ethlambda-types --lib: 232 passed. -p ethlambda-storage --lib: 211 passed, 1 ignored. -p ethlambda-state-transition --lib ssz_append_never_regrows, with and without preset-minimal: passed.

Related Issues / PRs

✅ Verification Checklist

  • Ran make fmt — clean
  • Ran make lint (clippy with -D warnings) — clean. Ran cargo clippy --locked -p ethlambda-types -p ethlambda-storage -p ethlambda-state-transition --all-targets -- -D warnings (clean), not the full workspace target
  • Ran make test (test-consensus plus test-node, at release-fast) — all passing. Ran only the tests above

@github-actions

Copy link
Copy Markdown

🤖 Claude Code Review

Review of PR 741: encode a beacon state without holding it twice

No blocking issues. The change is small and the reasoning holds.

  • Buffer sizing (containers/mod.rs, ssz_append_capacity): encoded_len() plus the largest fixed-size field is a sound bound on the headroom libssz's container encoder needs. The max is taken over every fixed-size field type, so a fork whose last field is fixed (fulu proposer_lookahead, gloas ptc_window) can't force a regrow. The largest field is RandaoMixes at about 2 MB. That is negligible next to a state of hundreds of MB.
  • Appending after the fork tag (state_codec.rs): encode_state_value now calls ssz_append into a buffer that already holds the 1-byte tag. This is only correct if libssz computes container offsets relative to where the append started, not to the start of the buffer. The new electra test covers it. It has variable-size fields, asserts bytes[1..] == to_ssz(), and round-trips through decode_state_value, so a wrong offset base would fail it.
  • Tests:
    • The fulu and gloas test asserts buf.capacity() == capacity, so a future libssz change that regrows the buffer will fail the test.
    • Both tests rely on Vec honouring with_capacity exactly. That is true in practice, but it is not guaranteed by the docs. The assertion is a reasonable regression guard.

Nits, non-blocking:

  • ssz_append_capacity runs encoded_len(), which walks the whole state. That is cheap next to the encode itself, but the doc comment could say so.
  • ssz_append_capacity is pub only for the storage crate's use. Keeping it that way is fine, but its doc comment should say that callers must pass a buffer with at least that much spare capacity.
  • The fixed-field list is hand-maintained. A new fork that adds a larger fixed-size field would silently bring back the double-hold. The capacity-assert tests would catch it only for forks they cover. Consider a short comment telling people to update the list when a fork adds a fixed-size field. Adding an electra and lean case to the first test would also help.

I haven't built the PR or run its tests.


Automated review by Claude (Anthropic) · sonnet · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Kimi Code Review

I'll review this PR which optimizes SSZ encoding for BeaconState to avoid buffer regrowth and double memory usage. Let me analyze each file.

crates/common/types/src/beacon/containers/mod.rs

Correctness Issues

Line 386-395 (ssz_append_capacity): The largest_fixed_field calculation is fragile and may become incorrect when new forks are added.

let largest_fixed_field = [
    <shared::RandaoMixes as libssz::SszEncode>::fixed_size(),
    <shared::BlockRoots as libssz::SszEncode>::fixed_size(),
    <altair::SyncCommittee as libssz::SszEncode>::fixed_size(),
    <gloas::PayloadTimelinessCommitteeWindow as libssz::SszEncode>::fixed_size(),
]

Problem: This hardcodes specific types from specific forks. If a future fork introduces a larger fixed-size field, this silently breaks. The comment mentions fulu's proposer_lookahead and gloas's ptc_window, but proposer_lookahead is not in this array.

Wait — let me re-read. The comment says "fulu's proposer_lookahead, gloas's ptc_window" but the array includes gloas::PayloadTimelinessCommitteeWindow (which is ptc_window) but no fulu::ProposerLookahead or equivalent. Is proposer_lookahead variable-size? If it's fixed-size and larger than the others, this is a bug.

Line 393: expect("the list is not empty") on a hardcoded array is fine, but consider unwrap_unchecked() or just unwrap() with a comment since it's a const-foldable property.

Documentation Issues

Line 369-370: Typo in comment — "fulu or gloas state" should be "Fulu or Gloas state" (capitalization inconsistent with rest of codebase).

Line 372: "which reserves only the encoding's length and so holds a fulu or gloas state twice while encoding it" — this is slightly misleading. The issue isn't the fork name, it's the encoder's write-past-end behavior for fixed-size fields after variable-size fields.

Testing

Lines 2226-2243: The test ssz_append_never_regrows_a_buffer_with_its_capacity_to_spare has a subtle issue:

assert_eq!(buf.capacity(), capacity, "{fork}: ssz_append regrew");

This assertion is too strict. Vec::capacity() can be larger than requested; the allocator may round up. This test may spuriously fail on different allocators or platforms. You should assert buf.capacity() >= capacity or buf.capacity() == capacity with a comment acknowledging this is implementation-dependent.

Similarly for encoded.capacity() on line 2242.

crates/storage/src/state_codec.rs

Correctness and Performance

Line 31:

let mut bytes = Vec::with_capacity(1 + state.ssz_append_capacity());

This is correct and achieves the optimization goal.

Line 33-34:

bytes.push(state.fork_name().selector());
state.ssz_append(&mut bytes);

Correct ordering: selector byte first, then SSZ payload.

Testing

Line 73-88: Same issue as above — bytes.capacity() assertion is too strict and may fail on different allocators.

Line 82: assert_eq!(bytes[1..], state.to_ssz()) — this verifies equivalence with the old path, which is good for regression testing.

Cross-Cutting Concerns

API Design

The new ssz_append and ssz_append_capacity methods expose libssz implementation details (the write-past-end behavior) at the BeaconState level. This creates a tight coupling. Consider:

  1. Whether libssz itself should provide an append_to API with proper capacity hinting
  2. Whether ssz_append_capacity should be pub — it's currently pub in mod.rs, making it part of the crate's public API

Memory Safety

No issues. The &mut Vec<u8> pattern is safe and idiomatic.

Consensus Criticality

This is not consensus-critical code — it's an encoding optimization. The actual SSZ bytes produced are identical; only the memory allocation pattern changes. The test verifies this equivalence.

Summary

Severity Issue Location
Medium capacity() equality assertions are too strict, may spuriously fail mod.rs:2239,2242, state_codec.rs:83
Low proposer_lookahead mentioned but not in largest_fixed_field array — verify if this is correct mod.rs:comment at 380
Low Typo in doc comment ("a fulu or gloas state") mod.rs:370
Low ssz_append_capacity exposes libssz internals as public API mod.rs:388

Recommendations

  1. Fix capacity assertions (most important):

    // Instead of:
    assert_eq!(buf.capacity(), capacity, ...);
    // Use:
    assert!(buf.capacity() >= capacity, "{fork}: ssz_append regrew: got {}, expected {}", buf.capacity(), capacity);
  2. Verify proposer_lookahead: Confirm whether Fulu's proposer_lookahead is fixed-size and if so, whether it could exceed the current largest_fixed_field. If it's variable-size, update the comment to clarify.

  3. Consider making ssz_append_capacity pub(crate) if external callers don't need it.

  4. Add a compile-time or macro-generated check for largest_fixed_field that fails when new forks are added with larger fixed fields, rather than relying on manual maintenance.


Automated review by Kimi (Moonshot AI) · kimi-k2.6 · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Codex Code Review

Review

  • Looks good overall. The patch is tightly scoped to SSZ serialization/storage buffering, and I don’t see any direct consensus-risk changes to fork choice, attestation processing, justification/finalization, state transition logic, XMSS handling, or SSZ decoding semantics.

  • crates/common/types/src/beacon/containers/mod.rs:391 looks correct: ssz_append_capacity() intentionally over-allocates by the largest fixed-size field to cover libssz’s temporary write-past-end behavior for trailing fixed-size fields. Since the serialized bytes still come from ssz_append, output compatibility should be preserved.

  • crates/storage/src/state_codec.rs:31 is a solid performance win. Writing SSZ directly into the tagged buffer avoids the extra full-state allocation/copy from extend_from_slice(&state.to_ssz()), which matters for large mainnet states.

  • Maintainability concern at crates/common/types/src/beacon/containers/mod.rs:392: the largest_fixed_field list is hand-maintained. If a future fork adds a larger trailing fixed-size field and this list is not updated, the code still works functionally but silently loses the no-regrowth guarantee. I’d suggest a short invariant comment or a broader regression test covering all fork fixtures.

  • Related point at crates/common/types/src/beacon/containers/mod.rs:393: the optimization depends on a non-obvious libssz implementation detail. The existing doc comment helps, but a test or helper closer to each fork’s definition would make future changes safer.

  • No security red flags: no new decoding surface, no weakened validation, and reduced peak memory pressure is a net positive for node robustness.

  • I couldn’t run the targeted tests here because cargo attempted to write to a read-only Rustup temp path in this environment; that looks environmental rather than PR-related.

If you want, I can convert this into a concise ready-to-post GitHub review comment.


Automated review by OpenAI Codex · gpt-5.4 · custom prompt

MegaRedHand added a commit that referenced this pull request Oct 30, 2026
libssz's container encoder writes each fixed-size field past the end of
the buffer and then moves it into place, and its to_ssz reserves only the
encoding's length. Fulu's state ends on a fixed-size field
(proposer_lookahead) and so does gloas's (ptc_window), so encoding either
regrows a buffer the size of the whole state to twice that for its last
field, copying it. Encoding a 44 MB fulu state ended with an 88 MB
buffer.

BeaconState now reserves the encoding's length plus its largest
fixed-size field (ssz_append_capacity) and appends into that, so
to_ssz never regrows; the Beacon API's SSZ state response goes through
it. The storage layer's encode_state_value, which runs on every import,
appends behind its fork tag into one such buffer instead of copying a
separately encoded state, which removed a second state-sized copy from
the follower's per-slot memory spike.

Cherry-picked from fix/types-state-encode-without-regrowth at 699f77a.
@pablodeymo

Copy link
Copy Markdown
Collaborator

Looked at this against libssz at 5cb1437. The bound is right: append_fixed
overhangs by exactly the field's size, and the derive's all-fixed fast path
means a nested fixed container (SyncCommittee, Checkpoint, ...) adds no
second layer, so "largest fixed-size field" is tight. Mainnet's is
randao_mixes (2 MiB), minimal's is ptc_window (3072 bytes, above
randao_mixes at 2048), and the minimal CI run covers the no-regrow assert.
No security concern: nothing here touches untrusted input, and the SSZ state
endpoint now peaks at one state plus 2 MiB per request instead of two states.

Two low-priority notes, neither blocking:

  1. ssz_append_capacity names four types by hand. A future fork that adds a
    fixed-size field larger than those would silently lose the no-regrow
    guarantee, and the test only covers fulu, gloas and (through the codec
    test) electra. Iterating every fork in
    ssz_append_never_regrows_a_buffer_with_its_capacity_to_spare would turn
    that into a test failure rather than a quiet regression.
  2. The spare capacity rides along in anything that keeps the returned Vec,
    such as the state writer's snapshot_memo. At 2 MiB next to a
    hundreds-of-MB state that is fine, and shrink_to_fit would cost the copy
    this PR removes, so just noting it.

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

@pablodeymo thanks for checking the bound against libssz.

  1. Every fork: ec13e5d6a. The test keeps its name but moved to state_transition's helpers/test_state.rs, since ethlambda-types can't build a state of every fork. It runs phase0 through gloas on both presets, plus a lean genesis since 1389f9a4b.
  2. The spare capacity in snapshot_memo: left as it is, per your note.

Three more from a second review pass:

  • 5fbfed2a1: ssz_append reserves its own room past the buffer's current length. A caller can no longer forget ssz_append_capacity or miscount a prefix, and to_ssz and encode_state_value no longer compute it.
  • 1389f9a4b: a lean state reserves its own largest fixed field, a block header, instead of the 2 MiB a mainnet beacon state needs. It does need some: with none, the test's lean case regrows.
  • 9b6c03b55: plan_beacon_state_write cloned the encoded target at every snapshot, one copy for the row and one for the memo. The writer now puts it into the batch from a borrow, through a new StorageWriteBatch::put, and moves the same buffer into the memo. A snapshot write holds the state plus RocksDB's batch copy, not three copies.

Fixing the overhang in libssz itself would also cover blocks and sidecars. I left that for a separate libssz PR, since it needs a rev bump.

MegaRedHand added a commit that referenced this pull request Nov 5, 2026
…view fixes

- test(types): check the no-regrow capacity against every fork. The test
  covered fulu and gloas only; it now builds a small state of every fork
  (the hard case, little variable-size data after each fixed field) and
  lives with the state-transition crate's test builders.
- fix(types): have ssz_append reserve its own room. Callers no longer size
  the buffer with ssz_append_capacity and add their own prefix to it; one
  that forgot regrew a state-sized buffer and held two copies, the spike
  this change removes. to_ssz and the state codec no longer compute it.
- fix(types): size a lean state's encode headroom from its own fields. A
  lean state reserved the largest fixed field of any beacon fork (2 MiB on
  mainnet) for every snapshot and to_ssz; it now reserves its own.
- fix(storage): write a beacon snapshot without cloning it for the memo.
  plan_beacon_state_write cloned the encoded target for the States row and
  the writer's snapshot memo. The plan now hands over one buffer and a
  flag; the writer puts it into the batch from a borrow
  (StorageWriteBatch::put takes slices) and moves the same buffer into the
  memo.

Updates nightly's #741 from fix/types-state-encode-without-regrowth at
699f77a to 9b6c03b (the branch head, 3834211, adds only a merge of
main).

Claude-Session: https://claude.ai/code/session_011vghNmndKPkZinHRkVTwVB
@MegaRedHand
MegaRedHand changed the base branch from main to fix/storage-latest-messages-exact-growth November 17, 2026 22:07
@MegaRedHand
MegaRedHand added this pull request to stack #798 November 17, 2026 22:12
@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

/review

@github-actions

Copy link
Copy Markdown

🤖 Codex Code Review

No actionable findings. The changes preserve SSZ serialization and snapshot memo behavior while reducing buffer copies. No consensus processing or signature verification logic changes.

Tests could not run: the pinned Rust toolchain attempted to write to the read-only /home/runner/.rustup/tmp directory.


Automated review by OpenAI Codex · gpt-6.1-sol · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Claude Code Review

Review: PR 741, avoiding double-buffering when encoding and storing beacon states

The PR does what it sets out to do. Peak memory on the snapshot path drops from about three copies of the state to two:

  • Before: to_ssz, then extend_from_slice into bytes, then target.clone(), then the RocksDB batch copy.
  • After: one tagged buffer, plus the RocksDB batch copy.

Nothing in it touches consensus logic. The comments below are about robustness and type design.

1. StateWrite { snapshot, memoize_snapshot } allows an illegal combination

File: state_writer.rs, around lines 81–93 and 700–716.

memoize_snapshot: true with snapshot: None can be represented. If that happens, the memo is silently left stale; the old match falls into the None arm. Today only plan_beacon_state_write sets the flag, and it does so correctly. Still, a type that rules this out would be cleaner. For example:

pub snapshot: Option<Snapshot>,
pub(crate) struct Snapshot { bytes: Vec<u8>, memoize: bool }

Alternatively, add a debug_assert!(!write.memoize_snapshot || write.snapshot.is_some()) before the match.

2. The memo now keeps the encoder's headroom as dead capacity

File: state_writer.rs, around line 724 (self.snapshot_memo = Some((root, encoded))).

The memoized Vec was previously target.clone(), which had exact capacity. It is now the ssz_append buffer, so it carries largest_fixed_field() of unused capacity for as long as it is the memo. On mainnet, randao_mixes makes that about 2 MiB. This is negligible next to the state itself, so I would not add shrink_to_fit (it would realloc and copy). It is worth one line in the memoize_snapshot doc comment so nobody is surprised later.

3. Exact-capacity assertions rely on unspecified reserve_exact behavior

Files: test_state.rs (assert_eq!(encoded.capacity(), capacity) and the framed check) and state_codec.rs (a_beacon_state_value_is_its_tag_then_its_ssz_in_one_buffer).

The comments acknowledge that the docs only promise "at least". You can make the test independent of that while still detecting a regrow:

let mut framed = vec![0xAB];
framed.reserve_exact(state.ssz_append_capacity());
let (ptr, cap) = (framed.as_ptr(), framed.capacity());
state.ssz_append(&mut framed); // its own reserve_exact is now a no-op
assert_eq!((framed.as_ptr(), framed.capacity()), (ptr, cap), "{fork}: regrew");

This checks only the property you care about: the append must not reallocate when given the advertised headroom. It does not depend on what reserve_exact rounds to.

4. largest_fixed_field is a hand-maintained list, and coverage depends on preset

File: containers/mod.rs, around lines 404–421.

The test catches a new oversized fixed field, but only for the preset the tests are compiled with. The comment says ptc_window beats randao_mixes only on minimal. If CI runs only one preset, a regression on the other preset would go unnoticed. That would cost performance, not correctness, since a regrow still produces correct bytes.

Consider adding a short note next to the list saying "keep in sync when a fork adds a fixed-size field". Alternatively, confirm that CI runs this test under both presets.

On the lean side, it is worth double-checking that State has no fixed-size Vector/Bitvector field larger than StateConfig, BlockHeader or Checkpoint. The lean genesis test case should catch this, but only if such a field sits after the variable-size data.

5. Default StorageWriteBatch::put copies the value

File: traits.rs, around lines 100–108.

The default copies both key and value into owned Vecs, which is correct. For an in-memory backend that has to own the bytes anyway, this is unavoidable. A one-line note would help: backends that can borrow (as RocksDB does) should override it, otherwise the snapshot path silently regains a full-state clone.

6. Minor points

  • ssz_append_capacity calls encoded_len on every append, and libssz's inner ssz_append likely computes it again. For beacon state lists of fixed-size elements this is O(1) per field, so it is fine.
  • The test in test_state.rs lives in a helper module. The doc comment justifies this, and it is acceptable.
  • In the RocksDB put (rocksdb.rs lines 222–230), the CF lookup and error message duplicate put_batch and delete_batch. A small fn cf(&self, table) helper would remove three copies. This is optional.

The one item I'd change is Item 1, plus the test-robustness tweak in Item 3; the rest is documentation and optional cleanup. Otherwise the PR looks good to merge.


Automated review by Claude · claude-opus-5-5 · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Grok Code Review

I'll inspect the SSZ append path and the state-writer changes against the surrounding types so the review is grounded in how those buffers are actually used.


Automated review by Grok (xAI) · grok-4.7 · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Gemini Code Review

The changes look solid and well-tested.

  • BeaconState::ssz_append / ssz_append_capacity (crates/common/types/src/beacon/containers/mod.rs): Pre-reserving encoded_len() + largest_fixed_field() cleanly avoids the late buffer doubling caused by libssz's container encoder appending fixed-size fields at the tail of the buffer before moving them into the fixed region.
  • encode_state_value (crates/storage/src/state_codec.rs): Appending directly after the fork selector byte avoids holding two copies of the encoded state during framing.
  • StorageWriteBatch::put & StateWriter (crates/storage/src/api/traits.rs, crates/storage/src/backend/rocksdb.rs, crates/storage/src/state_writer.rs): Replacing StateWrite::encoded with memoize_snapshot and writing to RocksDBWriteBatch via borrowed slices eliminates the snapshot clone when updating snapshot_memo.
  • Tests (crates/blockchain/state_transition/src/beacon/helpers/test_state.rs, crates/storage/src/backend/tests.rs, crates/storage/src/state_codec.rs): Good coverage verifying exact capacity across all forks (including Lean) and testing StorageWriteBatch::put.

Automated review by Gemini · gemini-4-argon · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 DeepSeek Code Review

Overall this PR is a solid memory optimization: it avoids holding two copies of a large beacon state during SSZ encoding and snapshot writes, and the tests cover the main invariant well.

A few points worth considering:

  1. largest_fixed_field is a hand-maintained list of SSZ fields. In crates/common/types/src/beacon/containers/mod.rs, the method hard-codes RandaoMixes, BlockRoots, SyncCommittee, and PayloadTimelinessCommitteeWindow. This is brittle across fork/preset changes. If a future fork adds a fixed-size field larger than those listed, ssz_append_capacity will silently under-reserve and the buffer will regrow, defeating the optimization. Since this is blockchain code where fork evolution is normal, prefer deriving the maximum over the full SSZ field layout for each fork, or at least add a test that scans the schema and asserts the hard-coded bound is still the maximum.

  2. The equality assertions on Vec::capacity rely on reserve_exact allocating exactly the requested capacity. This appears in crates/blockchain/state_transition/src/beacon/helpers/test_state.rs and crates/storage/src/state_codec.rs. While Rust’s current RawVec/global allocator behavior usually makes this true, Vec::reserve_exact only guarantees capacity >= len + additional, not exact equality. This is a minor test fragility if a custom allocator or future Vec implementation overallocates.

  3. BeaconState::to_ssz now returns a Vec with spare capacity beyond its length. This is intentional to avoid reallocation during encoding, but long-lived buffers — such as the snapshot memo in crates/storage/src/state_writer.rs — will retain that spare capacity. For beacon states the extra is roughly the largest fixed field, so usually acceptable. It may be worth a short comment in to_ssz noting that callers should not assume capacity() == len().

  4. The default StorageWriteBatch::put clones key/value. This is safe and documented, but it means non-RocksDB backends do not actually avoid a clone. That may be fine for now; just be aware the optimization is only fully realized by the RocksDB override.

  5. memoize_snapshot as a bool is workable but slightly less type-safe than the previous encoded: Option<Vec<u8>>. The current call sites are consistent, so this is only a maintainability observation, not a bug.

No consensus-level correctness issues found in this diff: the SSZ content is unchanged, and the state-transition path is only affected by allocation behavior, not serialization semantics.


Automated review by DeepSeek · deepseek-v4-pro · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Kimi Code Review

No blocking correctness, security, or consensus issues found. The RocksDB borrowed write copies into the write batch as documented, and moving the snapshot into the memo only after commit() preserves the previous ownership and failure behavior.

  • Brittle capacity assertions: ssz_append_never_regrows_a_buffer_with_its_capacity_to_spare in test_state.rs and a_beacon_state_value_is_its_tag_then_its_ssz_in_one_buffer in state_codec.rs assert exact Vec capacities. Vec::reserve_exact only guarantees capacity of at least len + additional; an implementation may legally provide more. Consequently, these tests can fail even when no regrowth occurred. The comment claiming std’s Vec always takes exactly the requested amount should also be softened. Prefer testing pointer stability: pre-reserve the buffer, save as_ptr(), append, and assert the pointer is unchanged, while retaining the encoding and round-trip assertions. This directly detects reallocation without relying on unspecified capacity behavior.

Otherwise, the fixed-field headroom is clearly documented, the storage default remains correct for non-RocksDB backends, and the snapshot-memo refactor avoids the large clone without changing write semantics.


Automated review by Kimi (Moonshot AI) · kimi-k3.1-pro · custom prompt

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

/review

@github-actions

Copy link
Copy Markdown

🤖 Codex Code Review

No actionable findings. The changes preserve SSZ encoding and storage commit ordering while reducing full-state allocations and copies. No consensus logic changes.

Tests could not run because rustup attempted to write to a read-only directory.


Automated review by OpenAI Codex · gpt-6.1-sol · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Claude Code Review

Review: PR 741 (encode beacon state snapshots without a second full copy)

The goal is sound: avoid holding two copies of a hundreds-of-MB state during encoding and storage. The approach works and is well tested. My main concerns are the coupling to libssz internals and one representable-invalid-state in StateWrite.

Correctness / design

  1. The fix depends on undocumented libssz internals (containers/mod.rs, ssz_append_capacity / largest_fixed_field). The headroom bound assumes libssz writes each fixed-size field past len and then moves it into place.

    • It also assumes nested containers don't compound that overshoot. For example, SyncCommittee or a header encoder doing the same trick while the outer field is already past the end.
    • The test guards the current version. Still, the real fix belongs upstream: libssz's to_ssz should reserve its own worst case, or write fixed fields in place.
    • Consider opening an issue on libssz and adding a // TODO(libssz#…) here, so this hand-maintained list can eventually go away.
  2. memoize_snapshot makes an invalid state representable (state_writer.rs ~L84–97, ~L704–725). The flag duplicates information already present.

    • Per the doc, it is true exactly when the state is beacon and snapshot.is_some(). Both are already known at commit time.
    • You could derive it instead of storing it:
      let memoize = !matches!(&*request.state, BeaconState::Lean(_));
      let memo = match write.snapshot {
          Some(snapshot) if memoize => { batch.put(Table::States, &key, &snapshot)...; Some(snapshot) }
          ...
      };
    • That removes the debug_assert! and the "flag true but snapshot None" case entirely.
    • If you want the plan to stay explicit, prefer a type that can't disagree with itself, e.g. snapshot: Option<(Vec<u8>, Memoize)>.
  3. to_ssz now returns a Vec with spare capacity for every caller (containers/mod.rs ~L375). On mainnet that is roughly 2 MiB of randao_mixes headroom.

    • This is fine for transient uses (hashing, snappy, storage).
    • Audit any caller that retains to_ssz() output, such as caches, req/resp responses, or checkpoint-sync serving. Each retained buffer now carries the headroom, and any into_boxed_slice() / shrink_to_fit() downstream silently reintroduces the copy.
    • Alternatively, use the headroom path only in encode_state_value. Pre-fulu forks end with a variable-size field (pending_consolidations), so per your own analysis they never regrew. Plain to_ssz was only a problem for fulu and gloas.

Minor

  1. largest_fixed_field beacon arm (~L417): this applies SyncCommittee and PayloadTimelinessCommitteeWindow to phase0 and other forks that lack those fields. It's harmless overreservation and the doc explains it, so no change is needed. It's just worth noting the list is a superset, not "the largest field of this variant" as the first doc line claims.

  2. rocksdb.rs put (~L222): the cf_handle lookup and error formatting are now copy-pasted a third time. A small fn cf(&self, table) -> Result<Arc<BoundColumnFamily>, Error> helper would tidy this.

  3. traits.rs default put: the comment warns that the default clones, which is good. If there's an in-memory backend used outside tests, override it there too. Otherwise snapshot writes through it quietly double peak memory.

  4. Test ssz_append_never_regrows... (test_state.rs):

    • The empty-prefix iteration's outer reserve_exact(capacity) makes the inner reserve_exact in ssz_append a no-op. So the test checks "capacity suffices", not "ssz_append reserves it". That's the right thing to test, just worth knowing.
    • The doc says "run on both presets". Make sure CI actually runs this crate with the minimal-preset feature, since that's where ptc_window beats randao_mixes.
  5. state_codec.rs test: the capacity() >= 1 + ssz_append_capacity() assertion is a reasonable way to detect "appended in place". It is somewhat indirect, but acceptable given the cross-reference to the real regrowth test.

Summary

Items 1 and 2 are worth addressing before merge (item 2 is an easy simplification). Item 3 needs at least an audit of retaining callers. The rest are nits.


Automated review by Claude · claude-opus-5-5 · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Grok Code Review

I'll inspect the surrounding encoding and state-writer paths so the review is based on how these changes actually behave, not just the diff.


Automated review by Grok (xAI) · grok-4.7 · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Gemini Code Review

This PR looks good. The root cause of the buffer regrowth during libssz container encoding and the extra state clones on the snapshot persistence path are both cleanly addressed:

  • BeaconState::ssz_append / ssz_append_capacity: Pre-reserving encoded_len() + largest_fixed_field() prevents libssz's fixed-field staging at the tail of the buffer from triggering a full-buffer reallocation on trailing fixed-size fields (such as proposer_lookahead in Fulu or ptc_window in Gloas), and allows encode_state_value to serialize directly after the 1-byte fork selector without allocating an intermediate Vec<u8>.
  • StorageWriteBatch::put and StateWrite::memoize_snapshot: Borrowing the snapshot buffer when writing to RocksDBWriteBatch allows moving the same Vec<u8> directly into StateWriter::snapshot_memo, eliminating the full-state .clone() on anchor writes.
  • Test coverage: ssz_append_never_regrows_a_buffer_with_its_capacity_to_spare verifies pointer and capacity stability across all beacon forks and Lean (both with and without the 1-byte prefix), which will catch any future fork introducing a larger fixed-size field.

Automated review by Gemini · gemini-4-argon · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 DeepSeek Code Review

No blocking issues found in this PR. The core idea — reserving encoded_len() + largest_fixed_field() before libssz appends, then using borrowed writes so the snapshot memo doesn’t clone a full state — is sound.

A few non-blocking observations:

  • crates/common/types/src/beacon/containers/mod.rs, largest_fixed_field: the hand-maintained list is the riskiest part. If a future fork adds a larger fixed-size field and someone forgets this list, the failure mode is a silent buffer regrow, not a correctness bug. The test in crates/blockchain/state_transition/src/beacon/helpers/test_state.rs is good and should catch that, but only if it runs on both presets and for every fork in CI.

  • crates/storage/src/state_writer.rs, StateWriter::commit: the invariant “memoize_snapshot implies snapshot.is_some()” is guarded only by debug_assert!. That’s fine given the current constructors, but in release a violation would leave a stale snapshot_memo, which could corrupt subsequent diffs. Since this is a blockchain client, I’d consider a normal assert! or returning an error here.

  • crates/storage/src/api/traits.rs: the new put default clones both key and value, so backends that don’t override it still pay the full-state clone on the snapshot path. The docs acknowledge this, but if there are any non-RocksDB production backends, this optimization won’t apply to them.

  • BeaconState::to_ssz now intentionally returns a Vec<u8> whose capacity() exceeds len(). That’s documented and is a reasonable tradeoff, but it’s worth being aware that any caller retaining such a Vec for a long time now retains the headroom too. The snapshot memo specifically avoids shrink_to_fit for this reason.

Overall, the SSZ/state-storage change looks correct and well-tested.


Automated review by DeepSeek · deepseek-v4-pro · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Kimi Code Review

No blocking issues found. The changes look correct and well tested:

  • crates/common/types/src/beacon/containers/mod.rs: reserve_exact is correctly applied relative to the buffer’s current length, including prefixed buffers. The all-fork SSZ round-trip and pointer/capacity assertions cover the important encoding and allocation invariants. If the hand-maintained fixed-field bound becomes stale, the consequence is a reallocation—not incorrect SSZ or unsafe memory access.
  • crates/storage/src/backend/rocksdb.rs and state_writer.rs: RocksDB copies the borrowed bytes into its batch before the snapshot buffer is moved into the memo. Memo publication still occurs only after a successful commit, and the debug assertion documents the snapshot/memo invariant.
  • The default StorageWriteBatch::put remains correct for backends without a borrowed-byte implementation, while the RocksDB override removes the intended full-state clone.

The performance trade-off of retaining roughly 2 MiB of encoder headroom in snapshot buffers is explicit and reasonable compared with cloning or regrowing a mainnet state.


Automated review by Kimi (Moonshot AI) · kimi-k3.1-pro · custom prompt

libssz's container encoder writes each fixed-size field past the end of
the buffer and then moves it into place, and its to_ssz reserves only the
encoding's length. Fulu's state ends on a fixed-size field
(proposer_lookahead) and so does gloas's (ptc_window), so encoding either
regrows a buffer the size of the whole state to twice that for its last
field, copying it. Encoding a 44 MB fulu state ended with an 88 MB
buffer.

BeaconState now reserves the encoding's length plus its largest
fixed-size field (ssz_append_capacity) and appends into that, so
to_ssz never regrows; the Beacon API's SSZ state response goes through
it. The storage layer's encode_state_value, which runs on every import,
appends behind its fork tag into one such buffer instead of copying a
separately encoded state, which removed a second state-sized copy from
the follower's per-slot memory spike.
The test covered fulu and gloas only, so a later fork with a fixed-size
field larger than any ssz_append_capacity counts would have lost the
guarantee without failing anything. It now builds a small state of every
fork, the hard case since little variable-size data follows each fixed
field, and lives with the state-transition crate's test builders because
ethlambda-types cannot build a state of every fork.
Each caller had to remember to size the buffer with ssz_append_capacity,
and to add its own prefix to it. One that forgot (vec![tag] and then
ssz_append, or a reserve of encoded_len only) regrew a buffer the size
of the state and held two copies of it, the very spike this change set
out to remove. ssz_append now reserves the room past the buffer's current
length itself, so a prefix is covered, and to_ssz and the state codec no
longer compute it.
Every variant reserved the largest fixed-size field of any beacon fork,
2 MiB on mainnet, including a lean state, whose widest fixed field is a
block header. Each lean snapshot and to_ssz of a lean state allocated
megabytes it never used, often more than the state itself. A lean state
now reserves its own largest fixed field. The beacon forks keep one
shared list, since every one of them has randao_mixes and a list per fork
would save at most a kilobyte on minimal.

The every-fork test now covers a lean genesis too; with no headroom for
it, that case regrows.
plan_beacon_state_write cloned the encoded target at every snapshot, one
copy for the States row and one for the writer's snapshot memo, so a
snapshot write still held a mainnet state twice, plus RocksDB's own copy
in the batch. The plan now hands over one buffer and a flag. The writer
puts it into the batch from a borrow, through a new
StorageWriteBatch::put that takes slices (RocksDB copies the value into
its batch either way), and then moves the same buffer into the memo.
The floor is now the target plus the batch's copy until commit.
The automated review read the capacity equality as too strict and asked for >=. A regrow can only raise the capacity, so a lower bound would pass every regrow the tests exist to catch. The comments say so, and that the exactness is std Vec's behaviour rather than a documented promise of reserve_exact.
…pacity

Three reviewers in the second automated round still read the exact-capacity assertions as fragile, comment or not: reserve_exact promises only at least what it is asked for. The no-regrow test now reserves the advertised headroom itself, with and without a prefix, and asserts the buffer's address and capacity are the same after the append, which holds whatever reserve_exact rounds to. Dropping the headroom from ssz_append_capacity fails it at phase0.

The codec test keeps a lower bound only: its buffer holds ssz_append's headroom, so the encoding went in directly rather than being made apart and copied in. Whether the headroom suffices is the test above.
From the second automated review round:

- StateWrite can express memoize_snapshot without a snapshot, which would leave the memo stale; the commit now debug-asserts it never happens.
- memoize_snapshot says the memo keeps the encoder's headroom as spare capacity, and to_ssz that its capacity exceeds its length.
- StorageWriteBatch::put says a backend that can copy from a borrow should override the cloning default.
- largest_fixed_field says its lists are kept by hand and which test fails when a fork outgrows them.
@pablodeymo
pablodeymo force-pushed the fix/types-state-encode-without-regrowth branch from 09b8b70 to cec0651 Compare November 18, 2026 20:44
@pablodeymo
pablodeymo enabled stacked auto-merge November 18, 2026 20:51
@pablodeymo
pablodeymo added this pull request to the merge queue Nov 18, 2026
Merged via the queue into main with commit bf66e86 Nov 18, 2026
11 checks passed
@pablodeymo
pablodeymo deleted the fix/types-state-encode-without-regrowth branch November 18, 2026 21:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants